Parent | Child | Previous | Next
 
JavaScript

A5.ListBoxsetGroupCollapse Method

Syntax

A5.ListBox.setGroupCollapse(group[,state[,animate]])

Arguments

groupstringobject

The name of the group or an object containing details on multiple groups to collapse or expand. If auto grouping is being used and more then on level of grouping is defined, then an the group name will be a concatinated string that includes all parent group names joined by a period. For example "USA.D" for sub-group "D" in group "USA".

groupsstring

Which groups to collapse or expand if multiple groups are being effected. Values can be "all", "level" or "match". If "all" is selected then all groups will be expanded or collapsed. If "level" is selected then only groups at the given level will be collapsed. If "match" is selected then each groups will be passed to a function to choose whether or not it matches the criterea.

levelnumber

If "groups" is equal to "level" then the level of groups to collapse or expand.

matchfunction(name,data)

If "groups" is equal to "match" then the function to choose which groups to collapse or expand.

namestring

The name of the group.

dataobject

The item data for the group.

statebooleannull

If true is passed in then the group will be collapsed, otherwise the group will be expanded. If no value (or null) is passed in then the group state will be toggled.

animateboolean

If true is passed in then the collapsing or expanding of the group will be done with animation.

Description

Set the collapse state of a group.

Example

// To get a pointer to the A5.ListBox class see {dialog.object}.getControl
// assume lObj is a pointer to an instance of the A5.ListBox class, and the list has multiple levels of auto grouping
lObj.setGroupCollapse(['B',1],true); // set the group with the name "B" in the second level of grouping to be false

The setGroupCollapse() method can be used to expand or collapse a group in a List control. Groups can be added to a List by enabling the Has client-side group breaks property. Groups can be expanded or collapsed only if the Can collapse groups property is enabled in the Client-side Grouping definition for the group.

To expand or collapse a group, you must reference the group name. For example, if the group is configured to break on a COUNTRY field in the list and you would like to collapse the 'Argentina' group, you could do the following:

var lObj = {dialog.object}.getControl('list1');
var groupName = 'Argentina';
var collapse = false;
var showAnimation = true;

lObj.setGroupCollapse(groupName,mode,showAnimation);

Where list1 is the ID of the List control you wish to expand the "Argentina" COUNTRY group.

You can also expand or collapse all groups in a List.

var lObj = {dialog.object}.getControl('list1')

lObj.setGroupCollapse({groups: 'all'},true,false); // collapse all groups without animation
lObj.setGroupCollapse({groups: 'all'},false,true); // expand all groups with animation

If the List has multiple levels of grouping, you can expand or collapse sub-groupings of lists. For example, assume a List is grouped by COUNTRY and then by CITY within each COUNTRY. All COUNTRY groups can be expanded as follows:

var lObj = {dialog.object}.getControl('list1');

// Expand all "Country" groups with animation:
lObj.setGroupCollapse({groups: 'level', level: 0},false,true);

level: 0 refers to the first level of grouping. COUNTRY is the first level of grouping described in our example. If you wanted to collapse all of the CITY groups within each country (level: 1), you could do the following:

var lObj = {dialog.object}.getControl('list1');

// Collapse all "City" groups without animation:
lObj.setGroupCollapse({groups: 'level', level: 1},true,false);

You can also use a match function to collapse (or expand) specific groups in the List:

var lObj = {dialog.object}.getControl('list1');

var matchFunction = function (groupName, groupData) {
        if(groupName.match(/^[A-z]/)) return true; // match any group with a name starting with a character
        return false;
}
var collapse = true;

// collapse all groups that meet the criteria defined in matchFunction()
lObj.setGroupCollapse({groups: 'match', match: matchFunction}, collapse);